home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 050 / pp.arc / ARGLIB.DOC next >
Encoding:
INI File  |  1985-04-07  |  6.6 KB  |  208 lines
  1. [74036,3110]
  2. ARGLIB.DOC     16-Mar-85 6400         76
  3.  
  4.     Keywords: PORTABLE FILE ARGUMENTS CPM-80 CPM-86 MS-DOS TURBO
  5.     PASCALMT+ BSD UNIX PASCAL
  6.  
  7.                                                                 PAGE 1
  8.  
  9.  
  10.  
  11.            ArgLib - A Portable Pascal File Argument Library
  12.  
  13.                             15 March 1985
  14.  
  15.                            Willett Kempton
  16.  
  17.  
  18.  
  19.  
  20. What ArgLib Does
  21. ----------------
  22.  
  23.      Arglib provides a portable means of reading file arguments from
  24. the operating system command line into a Pascal program.  It also
  25. allows assignment of a name to a file variable and detection of empty
  26. files.  ArgLib became necessary because almost every company's version
  27. of Pascal has implemented these functions in a different way.  By
  28. calling ArgLib, rather than writing system-specific code in each
  29. program, software can be more easily moved across compilers, operating
  30. systems and computers.
  31.  
  32. ArgLib is currently available for:
  33.  
  34.   1. Turbo Pascal, CP/M-80, CP/M-86, MS-DOS
  35.   2. Pascal/MT+, Pascal/MT+86
  36.   3. Berkeley UNIX Pascal, pi, pc
  37.  
  38. Specifics on these implementations follow:
  39.  
  40.      1.  ArgLib.pas: Turbo pascal.  Tested with Turbo v 1 and v 2, on
  41.          CP/M-80, CP/M-86, and MS-DOS on a DEC Rainbow.  Requires a
  42.          minor modification (marked in the code) to switch among these
  43.          operating systems.  Also, a bug in 8-bit Turbo (v1, v2)
  44.          truncates any command line arguments past 31 characters.
  45.  
  46.      2.  ArgLibMT.pas: Pascal/MT+86 and Pascal/MT+.  Tested with MT+86
  47.          V 3.1.  Note that in the MT+ version, "argcount" must be
  48.          called prior to "argv".  This is the typical calling sequence
  49.          anyway, but is REQUIRED under MT+ systems.
  50.  
  51.      3.  ArgLibUX.pas: Berkeley UNIX Pascal.  Tested on Pascal version
  52.          3.0, using both the pi interpreter and the pc compiler on a
  53.          VAX 11/750 running BSD 4.1.
  54.  
  55.  
  56.  
  57. Procedures avaliable
  58. --------------------
  59.  
  60.      argcount: Argument count.  Function returning an integer count of
  61. how many file arguments were given on the command line.
  62.  
  63.      argv(count,name): Argument Value.  Procedure setting the variable
  64. "name" to argument number "count" from the command line.
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74. ArgLib  -- Portable file argument library                       PAGE 2
  75.  
  76.  
  77.  
  78.      resetOK(file,name): Assign, reset, and check.  Assign the file
  79. variable "file" to read from the external file or device named "name".
  80. If the external file is nonexistant or empty, return false.  Otherwise
  81. return true.
  82.  
  83.      For example, suppose that the user calls program "cp" with two
  84. files:
  85.  
  86.     A>CP FILEA FILEB
  87.  
  88.      argcount     --> returns the value  2
  89.      argv(1,name) --> sets "name" to 'FILEA           '
  90.      argv(2,name) --> sets "name" to 'FILEB           '
  91.      resetOK(f,name) --> resets f for reading from "name";
  92.                          if nonempty, return TRUE
  93.  
  94.      Note that under UNIX, argv(0,name) would set "name" to 'CP', but
  95. in the micro version it sets "name" to blank.
  96.  
  97.      Most pascal systems will require ArgLib to be included after the
  98. last variable of the main program and before the first procedure.
  99. After the include, the following symbols are available.
  100.  
  101. Symbols available to calling program
  102.  
  103.  const
  104.    MaxArgStrLen = 16; (* max chars per argument; VARIES WITH OS! *)
  105.  type
  106.    ArgStrType = packed array [1..MaxArgStrLen] of char;
  107.  
  108.  procedure argv(argn : integer; var name : ArgStrType);
  109.  
  110.  function argcount : integer;
  111.  
  112.  function resetOK (var f: text; name: ArgStrType) : boolean;
  113.  
  114.      Design tradeoffs were as follows.  Execution speed was sacrificed
  115. for compact code, since these routines will typically only be called
  116. once.  Standard Pascal (ISO standard) was used whenever possible (no
  117. 'string', etc.).  (Berkeley UNIX Pascal provides no string type.)
  118.  
  119.  
  120. Testing ArgLib
  121. --------------
  122.  
  123.      A test program is provided with ArgLib.  It is called ArgTest.pas
  124. and it includes ArgLib into its source.  The following is a session
  125. using argtest on CP/M:
  126.  
  127.  
  128. F>dir
  129. F: SMALL       : EMPTY       : ARGTEST.CMD
  130.  
  131. F>type empty
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141. ArgLib  -- Portable file argument library                       PAGE 3
  142.  
  143.  
  144.  
  145. F>type small
  146. this is a small file
  147.  
  148. F>type nothing
  149. NO FILE
  150. F>argtest empty small nothing
  151. file arguments=3
  152.  0=               empty
  153.  1= EMPTY         empty
  154.  2= SMALL         exists
  155.  3= NOTHING       empty
  156.  
  157. F>
  158.  
  159. Note that both the empty and the nonexistant files are detected.
  160.  
  161.  
  162. Hints for Portable Code
  163. -----------------------
  164.  
  165.      Some of the programs you write will only be used a few times, or
  166. by their nature, will only be used on one system.  These need not be
  167. portable.  Other programs will retain their value over a period of
  168. years.  During those years, you are likely to use different computers,
  169. and almost certain to use several different compilers.  To preserve
  170. your software-writing investment, you want to be able to transfer your
  171. programs without having to re-write them for each system.  Programs
  172. which allow easy transfer are considered "portable".
  173.  
  174.      For those programs which you want to be portable, do not use the
  175. compiler manufacturer's manual to guide your writing.  Use a manual on
  176. "Standard Pascal", which is a subset of most commercial Pascals.  The
  177. Standard is defined by ISO, the International Standards Organization,
  178. and by ANSI, the American member of ISO.  The defining ISO document
  179. (ISO dp7185, December 1980) is precise but difficult to read.  Two
  180. readable descriptions of Standard Pascal are available.  One is
  181. "Standard Pascal, User Reference Manual", by Doug Cooper, (1983, W.
  182. W.  Norton & Company).  The other is the THIRD edition of "Pascal User
  183. Manual and Report", by Jensen and Wirth (1984, Springer Verlag).
  184. Either is preferable to the second edition of Jensen & Wirth (1974),
  185. which is less readable and partially inconsistent with the final ISO
  186. standard.
  187.  
  188.      Sometimes, system dependent features will be necessary, for
  189. example in getting file names from the operating system command line.
  190. When they are needed, they can be localized in a few routines which
  191. can be called in a standard way.  Then to change all your software for
  192. a new system, you need only change a few routines.  ArgLib is an
  193. example of this strategy.
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PORTABLE FILE ARGUMENTS CPM-80 CPM-86 MS-DOS TURBO PASCALMT+ BSD UNIX
  203. These routines allow Pascal programs to get arguments (e.g. files,
  204. options) from the command line.  Works in all Turbo systems, with
  205. a one -line change (marked in comments).  Versions are also available
  206. for Pascal/MT+ and BSD UNIX pascal (request upload).
  207.  
  208.